<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<topic id="topic1">
    <!-- install guide has a link to this topic. -->
    <title id="jp20941">gpaddmirrors</title>
    <body>
        <p>Adds mirror segments to a Greenplum Database system that was initially configured without
            mirroring.</p>
        <section id="section2">
            <title>Synopsis</title>
            <codeblock>gpaddmirrors [-p &lt;port_offset>] [-m &lt;datadir_config_file> [-a]] [-s] 
   [-d &lt;master_data_directory>] [-b &lt;segment_batch_size>] [-B &lt;batch_size>] [-l &lt;logfile_directory>]
   [-v] [--hba-hostnames &lt;boolean>] 

gpaddmirrors -i &lt;mirror_config_file> [-a] [-d &lt;master_data_directory>]
   [-b &lt;segment_batch_size>] [-B &lt;batch_size>] [-l &lt;logfile_directory>] [-v]

gpaddmirrors -o output_sample_mirror_config> [-s] [-m &lt;datadir_config_file>]

gpaddmirrors -? 

gpaddmirrors --version</codeblock>
        </section>
        <section id="section3">
            <title>Description</title>
            <p>The <codeph>gpaddmirrors</codeph> utility configures mirror segment instances for an
                existing Greenplum Database system that was initially configured with primary
                segment instances only. The utility will create the mirror instances and begin the
                online replication process between the primary and mirror segment instances. Once
                all mirrors are synchronized with their primaries, your Greenplum Database system is
                fully data redundant.</p>
            <note type="important">During the online replication process, Greenplum Database should
                be in a quiescent state, workloads and other queries should not be running.</note>
            <p>By default, the utility will prompt you for the file system location(s) where it will
                create the mirror segment data directories. If you do not want to be prompted, you
                can pass in a file containing the file system locations using the
                    <codeph>-m</codeph> option.</p>
            <p>The mirror locations and ports must be different than your primary segment data
                locations and ports.</p>
            <p>The utility creates a unique data directory for each mirror segment instance in the
                specified location using the predefined naming convention. There must be the same
                number of file system locations declared for mirror segment instances as for primary
                segment instances. It is OK to specify the same directory name multiple times if you
                want your mirror data directories created in the same location, or you can enter a
                different data location for each mirror. Enter the absolute path. For example:</p>
            <codeblock>Enter mirror segment data directory location 1 of 2 &gt; /gpdb/mirror
Enter mirror segment data directory location 2 of 2 &gt; /gpdb/mirror</codeblock>
            <p>OR</p>
            <codeblock>Enter mirror segment data directory location 1 of 2 &gt; /gpdb/m1
Enter mirror segment data directory location 2 of 2 &gt; /gpdb/m2</codeblock>
            <p>Alternatively, you can run the <codeph>gpaddmirrors</codeph> utility and supply a
                detailed configuration file using the <codeph>-i</codeph> option. This is useful if
                you want your mirror segments on a completely different set of hosts than your
                primary segments. The format of the mirror configuration file is:</p>
            <codeblock>&lt;contentID>|&lt;address>|&lt;port>|&lt;data_dir></codeblock>
            <p>Where <codeph>&lt;contentID></codeph> is the segment instance content ID,
                    <codeph>&lt;address></codeph> is the host name or IP address of the segment
                host, <codeph>&lt;port></codeph> is the communication port, and
                    <codeph>&lt;data_dir></codeph> is the segment instance data directory.</p>
            <p>For
                example:<codeblock>0|sdw1-1|60000|/gpdata/m1/gp0
1|sdw1-1|60001|/gpdata/m2/gp1</codeblock></p>
            <p>The <codeph>gp_segment_configuration</codeph> system catalog table can help you
                determine your current primary segment configuration so that you can plan your
                mirror segment configuration. For example, run the following query:</p>
            <codeblock>=# SELECT dbid, content, address as host_address, port, datadir 
   FROM gp_segment_configuration
   ORDER BY dbid;</codeblock>
            <p>If you are creating mirrors on alternate mirror hosts, the new mirror segment hosts
                must be pre-installed with the Greenplum Database software and configured exactly
                the same as the existing primary segment hosts. </p>
            <p>You must make sure that the user who runs <codeph>gpaddmirrors</codeph> (the
                    <codeph>gpadmin</codeph> user) has permissions to write to the data directory
                locations specified. You may want to create these directories on the segment hosts
                and <codeph>chown</codeph> them to the appropriate user before running
                    <codeph>gpaddmirrors</codeph>.</p>
            <note>This utility uses secure shell (SSH) connections between systems to perform its
                tasks. In large Greenplum Database deployments, cloud deployments, or deployments
                with a large number of segments per host, this utility may exceed the host's maximum
                threshold for unauthenticated connections. Consider updating the SSH
                    <codeph>MaxStartups</codeph> configuration parameter to increase this threshold.
                For more information about SSH configuration options, refer to the SSH documentation
                for your Linux distribution.</note>
        </section>
        <section id="section4">
            <title>Options</title>
            <parml>
                <plentry>
                    <pt>-a (do not prompt)</pt>
                    <pd>Run in quiet mode - do not prompt for information. Must supply a
                        configuration file with either <codeph>-m</codeph> or <codeph>-i</codeph> if
                        this option is used.</pd>
                </plentry>
                <plentry>
                    <pt>-b <varname>segment_batch_size</varname></pt>
                    <pd>The maximum number of segments per host to operate on in parallel. Valid
                        values are <codeph>1</codeph> to <codeph>128</codeph>. If not specified, the
                        utility will start recovering up to 64 segments in parallel on each
                        host.</pd>
                </plentry>
                <plentry>
                    <pt>-B <varname>batch_size</varname></pt>
                    <pd>The number of hosts to work on in parallel. If not specified, the utility
                        will start working on up to 16 hosts in parallel. Valid values are
                            <codeph>1</codeph> to <codeph>64</codeph>.</pd>
                </plentry>
                <plentry>
                    <pt>-d <varname>master_data_directory</varname></pt>
                    <pd>The master data directory. If not specified, the value set for
                            <codeph>$MASTER_DATA_DIRECTORY</codeph> will be used.</pd>
                </plentry>
                <plentry>
                    <pt>--hba-hostnames <varname>boolean</varname></pt>
                    <pd>Optional. Controls whether this utility uses IP addresses or host names in
                        the <codeph>pg_hba.conf</codeph> file when updating this file with addresses
                        that can connect to Greenplum Database. When set to 0 -- the default value
                        -- this utility uses IP addresses when updating this file. When set to 1,
                        this utility uses host names when updating this file. For consistency, use
                        the same value that was specified for <codeph>HBA_HOSTNAMES</codeph> when
                        the Greenplum Database system was initialized. For information about how
                        Greenplum Database resolves host names in the <codeph>pg_hba.conf</codeph>
                        file, see <xref href="../../admin_guide/client_auth.html" format="html" scope="external">Configuring Client Authentication</xref>.</pd>
                </plentry>
                <plentry>
                    <pt>-i <varname>mirror_config_file</varname></pt>
                    <pd>A configuration file containing one line for each mirror segment you want to
                        create. You must have one mirror segment instance listed for each primary
                        segment in the system. The format of this file is as follows (as per
                        attributes in the <xref
                            href="../../ref_guide/system_catalogs/gp_segment_configuration.xml"
                            >gp_segment_configuration</xref> catalog table):</pd>
                    <pd>
                        <codeblock>&lt;contentID>|&lt;address>|&lt;port>|&lt;data_dir></codeblock>
                    </pd>
                    <pd>
                        <p>Where <codeph>&lt;contentID></codeph> is the segment instance content ID,
                                <codeph>&lt;address></codeph> is the hostname or IP address of the
                            segment host, <codeph>&lt;port></codeph> is the communication port, and
                                <codeph>&lt;data_dir></codeph> is the segment instance data
                            directory. For information about using a hostname or IP address, see
                                <xref href="#topic1/host_ip" format="dita"/>. Also, see <xref
                                href="#topic1/multi_nic" format="dita"/>.</p>
                    </pd>
                </plentry>
                <plentry>
                    <pt>-l <varname>logfile_directory</varname></pt>
                    <pd>The directory to write the log file. Defaults to
                            <codeph>~/gpAdminLogs</codeph>.</pd>
                </plentry>
                <plentry>
                    <pt>-m <varname>datadir_config_file</varname></pt>
                    <pd>A configuration file containing a list of file system locations where the
                        mirror data directories will be created. If not supplied, the utility
                        prompts you for locations. Each line in the file specifies a mirror data
                        directory location. For example:</pd>
                    <pd>
                        <codeblock>/gpdata/m1
/gpdata/m2
/gpdata/m3
/gpdata/m4</codeblock>
                    </pd>
                </plentry>
                <plentry>
                    <pt>-o <varname>output_sample_mirror_config</varname></pt>
                    <pd>If you are not sure how to lay out the mirror configuration file used by the
                            <codeph>-i</codeph> option, you can run <codeph>gpaddmirrors</codeph>
                        with this option to generate a sample mirror configuration file based on
                        your primary segment configuration. The utility will prompt you for your
                        mirror segment data directory locations (unless you provide these in a file
                        using <codeph>-m</codeph>). You can then edit this file to change the host
                        names to alternate mirror hosts if necessary.</pd>
                </plentry>
                <plentry>
                    <pt>-p <varname>port_offset</varname></pt>
                    <pd>Optional. This number is used to calculate the database ports used for
                        mirror segments. The default offset is 1000. Mirror port assignments are
                        calculated as
                        follows:<codeblock>primary_port + offset = mirror_database_port</codeblock></pd>
                    <pd>For example, if a primary segment has port 50001, then its mirror will use a
                        database port of 51001, by default.</pd>
                </plentry>
                <plentry>
                    <pt>-s (spread mirrors)</pt>
                    <pd>Spreads the mirror segments across the available hosts. The default is to
                        group a set of mirror segments together on an alternate host from their
                        primary segment set. Mirror spreading will place each mirror on a different
                        host within the Greenplum Database array. Spreading is only allowed if there
                        is a sufficient number of hosts in the array (number of hosts is greater
                        than the number of segment instances per host).</pd>
                </plentry>
                <plentry>
                    <pt>-v (verbose)</pt>
                    <pd>Sets logging output to verbose.</pd>
                </plentry>
                <plentry>
                    <pt>--version (show utility version)</pt>
                    <pd>Displays the version of this utility.</pd>
                </plentry>
                <plentry>
                    <pt>-? (help)</pt>
                    <pd>Displays the online help.</pd>
                </plentry>
            </parml>
        </section>
        <section id="host_ip">
            <title>Specifying Hosts using Hostnames or IP Addresses</title>
            <p>When specifying a mirroring configuration using the <codeph>gpaddmirrors</codeph>
                option <codeph>-i</codeph>, you can specify either a hostname or an IP address for
                the &lt;address> value. <ul id="ul_zsd_cmh_dmb">
                    <li>If you specify a hostname, the resolution of the hostname to an IP address
                        should be done locally for security. For example, you should use entries in
                        a local <codeph>/etc/hosts</codeph> file to map the hostname to an IP
                        address. The resolution of a hostname to an IP address should not be
                        performed by an external service such as a public DNS server. You must stop
                        the Greenplum system before you change the mapping of a hostname to a
                        different IP address.</li>
                    <li>If you specify an IP address, the address should not be changed after the
                        initial configuration. When segment mirroring is enabled, replication from
                        the primary to the mirror segment will fail if the IP address changes from
                        the configured value. For this reason, you should use a hostname when
                        enabling mirroring using the <codeph>-i</codeph> option unless you have a
                        specific requirement to use IP addresses.</li>
                </ul></p>
            <p>When enabling a mirroring configuration that adds hosts to the Greenplum system,
                    <codeph>gpaddmirrors</codeph> populates the <xref
                    href="../../ref_guide/system_catalogs/gp_segment_configuration.xml"
                    >gp_segment_configuration</xref> catalog table with the mirror segment instance
                information. Greenplum Database uses the <varname>address</varname> value of the
                    <codeph>gp_segment_configuration</codeph> catalog table when looking up host
                systems for Greenplum interconnect (internal) communication between the master
                and segment instances and between segment instances, and for other internal
                communication.</p>
        </section>
        <section id="multi_nic">
            <title>Using Host Systems with Multiple NICs</title>
            <p>If hosts systems are configured with multiple NICs, you can initialize a Greenplum
                Database system to use each NIC as a Greenplum host system. You must ensure that the
                host systems are configured with sufficient resources to support all the segment
                instances being added to the host. Also, if you enable segment mirroring, you must
                ensure that the Greenplum system configuration supports failover if a host system
                fails. For information about Greenplum Database mirroring schemes, see <xref
                    href="../../best_practices/ha.html#topic_ngz_qf4_tt" format="html" scope="external"/>.</p>
            <p>For example, this is a segment instance configuration for a simple Greenplum system.
                The segment host <codeph>gp6m</codeph> is configured with two NICs,
                    <codeph>gp6m-1</codeph> and <codeph>gp6m-2</codeph>, where the Greenplum
                Database system uses <codeph>gp6m-1</codeph> for the master segment and
                    <codeph>gp6m-2</codeph> for segment instances. </p>
            <codeblock>select content, role, port, hostname, address from gp_segment_configuration ;

 content | role | port  | hostname | address
---------+------+-------+----------+----------
      -1 | p    |  5432 | gp6m     | gp6m-1
       0 | p    | 40000 | gp6m     | gp6m-2
       0 | m    | 50000 | gp6s     | gp6s
       1 | p    | 40000 | gp6s     | gp6s
       1 | m    | 50000 | gp6m     | gp6m-2
(5 rows) </codeblock>
        </section>
        <section id="section5">
            <title>Examples</title>
            <p>Add mirroring to an existing Greenplum Database system using the same set of hosts as
                your primary data. Calculate the mirror database ports by adding 100 to the current
                primary segment port numbers:</p>
            <codeblock>$ gpaddmirrors -p 100</codeblock>
            <p>Generate a sample mirror configuration file with the <codeph>-o</codeph> option to
                use with <codeph>gpaddmirrors -i</codeph>:</p>
            <codeblock>$ gpaddmirrors -o /home/gpadmin/sample_mirror_config</codeblock>
            <p>Add mirroring to an existing Greenplum Database system using a different set of hosts
                from your primary data:</p>
            <codeblock>$ gpaddmirrors -i mirror_config_file</codeblock>
            <p>Where <codeph>mirror_config_file</codeph> looks something like this:</p>
            <codeblock>0|sdw1-1|52001|/gpdata/m1/gp0
1|sdw1-2|52002|/gpdata/m2/gp1
2|sdw2-1|52001|/gpdata/m1/gp2
3|sdw2-2|52002|/gpdata/m2/gp3</codeblock>
        </section>
        <section id="section6">
            <title>See Also</title>
            <p><xref href="./gpinitsystem.xml#topic1" type="topic" format="dita"/>, <xref
                    href="./gpinitstandby.xml#topic1" type="topic" format="dita"/>, <xref
                    href="gpactivatestandby.xml#topic1"/></p>
        </section>
    </body>
</topic>
